home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Amiga Amateur Radio User Group / AARUG UK #01 (1989-10)(Amiga Amateur Radio User Group UK)(PD)[m].zip / AARUG UK #01 (1989-10)(Amiga Amateur Radio User Group UK)(PD)[m].adf / Packer.DOC / Packer.DOC
Text File  |  1993-12-02  |  21KB  |  518 lines
  1.  
  2.                         Power Packer 2.2a User Manual
  3.  
  4.                                  May 8, 1989
  5.  
  6.  
  7.  
  8. Preface
  9. =======
  10.  
  11.      Congratulations, you have just obtained a copy of the PowerPacker 2.2a,
  12. Power Peak's command and data cruncher for the Amiga.
  13.      If you have suggestions or remarks about this program, or if you find
  14. any bugs, please let me know.
  15.      This version of the PowerPacker is shareware, this means that if you use
  16. it a lot I would appreciate it if you'd send me a contribution of $10 or the
  17. same amount in any other currency.  This money will enable me to produce more
  18. programs on the Amiga.  If you send $15 I will send you the latest version of
  19. the PowerPacker.
  20.      Write to the following address:
  21.  
  22.                                 Nico François
  23.                                 Corbielaan 13
  24.                              3060 Bertem BELGIUM
  25.  
  26.  
  27. Contents
  28. ========
  29.  
  30. 1. The Packer
  31.      1.1 An introduction
  32.      1.2 The file requester
  33.      1.3 The basic menus
  34.           1.3.1 Project
  35.           1.3.2 Prefs
  36.  
  37. 2. Recrunch
  38.      2.1 How ?
  39.      2.2 Why ?
  40.  
  41. 3. The HunkLab
  42.      3.1 Preferences
  43.      3.2 Process file
  44.  
  45. 4. The Script Menu
  46.  
  47. 5. The Supervisor Window
  48.  
  49. 6. A Sample Session
  50.  
  51. 7. PowerPacker 2.2a & the CLI
  52.  
  53.  
  54. 1. The Packer
  55. -------------
  56.  
  57. 1.1 An introduction
  58.  
  59.      The PowerPacker is a userfriendly command and data cruncher, this means
  60. a menu driven utility that can crunch almost any file on your disks.  When
  61. you use it for the first time it's best to maintain a certain order in your
  62. actions (as we will see in chapter 6 of this document):
  63.  
  64.   (a) Set the packer options at the beginning of a session (Prefs menu)
  65.   (b) Load the file from disk (Project menu)
  66.   (c) Wait for the file to (de)crunch.
  67.   (d) Save the file back to disk (Project menu)
  68.  
  69.      Apart from crunching, you can also recrunch files that were crunched by
  70. most other crunchers.
  71.      The HunkLab enables you to e.g. force code or data in chip ram.
  72.      The script allows you to e.g. crunch a dozen of files overnight.
  73.  
  74.      Before I demonstrate how to use the PowerPacker, let's look at the file
  75. requester and a brief overview of the menus and capabilities.
  76.  
  77.  
  78. 1.2 The file requester
  79.  
  80.     Whenever you are required to enter a filename, the packer sets up a file
  81. requester.  This requester automatically contains all devices connected to
  82. your Amiga and lists all the files (and their length) of a selected
  83. directory.  You don't have to wait for the directory read to end.  You can
  84. select a file or directory the moment you see it, or you can enter it in the
  85. appropriate string gadget.
  86.  
  87.     However, if you wait for the directory read to end and quit the file
  88. requester, the next time you use it all the files will still be there, so you
  89. don't have to wait for the directory to be read again (This is very useful
  90. when you are recording a script, as you'll see later).  This feature has one
  91. disadvantage :  if files are changed or added to the selected directory they
  92. won't be shown in the list, or they will be shown with the wrong filelength,
  93. the next time the requester appears.  Therefore, if you think anything has
  94. been changed to the selected directory, use the 'GET DIR' gadget to re-read
  95. the directory.  (E.g.  when you save a crunched file on top of the old one,
  96. the old file length will be shown in the requester.)
  97.  
  98.  
  99. 1.3 The basic menus
  100.  
  101. 1.3.1 Project
  102.  
  103.     The project menu contains the file manipulation options.  Most of them
  104. speak for themselves:
  105.  
  106.   Load      ->  Load a file from disk and start the (de)crunching.
  107.   Save      ->  Save the (de)crunched or processed file in memory to disk.
  108.   Delete    ->  Delete a file from disk.
  109.   WorkBench ->  Open or close WorkBench if possible. (Adds 42K !)
  110.   Sleep     ->  Put the PowerPacker to sleep on the WorkBench Screen, this
  111.                 frees 40-50K.
  112.                 WARNING: All buffers will be deallocated, so you are advised
  113.                          to save things first.
  114.   About...  ->  Show general information and my address.
  115.   Quit      ->  Quit the program.
  116.  
  117. 1.3.2 Prefs
  118.  
  119.      The prefs menu contains all the (de)cruncher settings.  You can select
  120. to (de)crunch command files or a data files.  If you want the crunched
  121. version of your file to be executable, select 'Command file'.  Now the
  122. PowerPacker knows it has to add a decrunch header (572 bytes).  If the file
  123. you want to crunch only contains data (e.g. Source codes of your own
  124. programs), select the 'Data file' option.  This can be handy if you're going
  125. to use the PowerPacker CLI commands.  I'll discuss these commands in chapter
  126. 5 of this document.  Finally you have to choose whether you want to crunch or
  127. decrunch the load file.
  128.  
  129. Note: - The PowerPacker will automatically decrunch a previously crunched
  130.         file.  You don't have to select crunch or decrunch mode anymore as
  131.         in PowerPacker 2.0a.
  132.  
  133.      The 'Decrunch Color' submenu contains the following options :
  134.  
  135.   Color 0   ->  The background color will change while decrunching
  136.   Color 1   ->  The text color changes
  137.   Pointer   ->  Only the mousepointer's color changes
  138.   Scroll    ->  Handy for decrunching a demo (just try it out !)
  139.   None      ->  If your eyes are wearing out.
  140.  
  141.      These options indicate what color will flash when a file is decrunched.
  142. You can change this option before saving a crunched file, so you can save a
  143. version of your crunched program that flashes in color 1, and one that
  144. flashes in the mouse pointer.
  145.      If the 'Color Crunch' option is selected, the PowerPacker will use the
  146. same color while crunching the file, giving you an idea what the decrunching
  147. will look like (provided that you don't change any options just before saving
  148. to disk).  The default value is 'Color 1'.
  149.  
  150.      In the efficiency submenu you will find the following possibilities :
  151.  
  152.   Fast      ->  Use for small files, or for quick crunch.
  153.   Mediocre  ->  Better but slower.
  154.   Good      ->  Default, gains 40-50% in most cases.
  155.   Very Good ->  Also very slow !
  156.   Best      ->  Advised for script use only, ultra slow !!!
  157.  
  158. Note: - 'Fast' is approx. 4 times faster than 'Good', 'Very Good' is
  159.         2 times slower and 'Best' 4 times.
  160.       - 'Best' isn't always the best.  Small files crunch best with
  161.         'Very Good' or even 'Good'.
  162.  
  163.      You can set Amiga's multitasking off to increase the crunching speed
  164. (slightly).  The default setting is on.  When you want to use the PowerPacker
  165. in a multitasking environment, you'll probably start a crunching job and at
  166. the same time continue your work.  In that case, it might be interesting to
  167. set the 'LED Crunch' option on.  Now your power-LED flashes while crunching,
  168. just like the screencolors.  (but I presume they're already turned off
  169. because editing a file with flashing text really gets on your nerves.)
  170.      You can even turn off your monitor and still see when the cruncher has
  171. finished.
  172.  
  173.      Finally, you can set 'Paging' in the supervisor window on so you can
  174. read the crunch and hunk information, without everything racing off the
  175. screen before you've had a chance to see it.
  176.  
  177. Note: - While crunching, you can press both mousebuttons at the same
  178.         time to abort.
  179.       - Do *NOT* change disks when you are crunching with the multitasking
  180.         switched off !!!  The Amiga will crash !!!
  181.  
  182. 2. Recrunch
  183. -----------
  184.  
  185. 2.1 How ?
  186.  
  187.      This menu is provided for the people who were using another cruncher or
  188. an older version of the PowerPacker.  Just select 'Recrunch File' or
  189. 'Decrunch Only' and load the file.  The PowerPacker will start the correct
  190. decrunch algorithm.  If you selected 'Recrunch' the PowerPacker will start to
  191. crunch the decrunched file.  If the PowerPacker doesn't recognize the
  192. cruncher it will say so, no harm is done.  If you select 'Recrunch Always'
  193. the PowerPacker will always recrunch, even if the file was crunched with this
  194. version of the PowerPacker.  Useful for recrunching files using a higher
  195. efficiency.  (E.g. recrunch a 'Fast' crunched file with 'Best')
  196.  
  197.      Crunchers currently supported are:  'ANC Cruncher', 'TNM Cruncher 1.1',
  198. 'Relokit 1.0', 'HQC Cruncher 2.0', 'MasterCruncher 3.0', 'DragPack 1.0' and
  199. older PowerPacker files.  If you'd like to see other crunchers supported,
  200. send me the cruncher and some programs crunched with it.  (Together with a
  201. contribution I hope).  If it is possible to develop a decrunch algorithm I
  202. will include it in the next version of the PowerPacker.
  203.  
  204. 2.2 Why ?
  205.  
  206.      The PowerPacker always crunches better than the 'ANC Cruncher',
  207. 'TNM Cruncher' and 'HQC Cruncher'.  It crunches better than 'Relokit' most of
  208. the time, but even if it doesn't, I advise you to recrunch because 'Relokit'
  209. has some serious disadvantages (e.g.  while the decrunched file is running,
  210. the crunched version still eats memory).  In contrast the PowerPacker only
  211. eats about 580 bytes while your file is running, and (of course) frees it
  212. afterwards.
  213.  
  214. Note: - If you want to recrunch a PowerPacker 1.1 or 2.0 crunched file, the
  215.         PowerPacker just replaces the file header with the improved and
  216.         debugged 2.2 header. (Unless you've selected 'Recrunch Always')
  217.       - The recrunch menu only supports command files !  You can't recrunch
  218.         data files from e.g. PowerPacker 1.0, sorry.
  219.  
  220. 2. The Hunklab
  221. --------------
  222.  
  223. 2.1 Preferences
  224.  
  225.      This menu is not really part of the PowerPacker crunch/decrunch routines
  226. but it wasn't worth writing a separate program for and a HunkLab is after all
  227. a very interesting utility.  You can e.g. use it to remove symbol and debug
  228. hunks from files that wouldn't crunch otherwise.
  229.  
  230.      You can force a program's code, data or BSS (uninitialised data) into
  231. chip ram or you can remove symbol tables and debug information just by
  232. toggling the marker on/off.  So in future, when you want your programs to be
  233. able to run on a one megabyte system, a simple click on the mousebutton will
  234. do.
  235.  
  236. 2.2 Process file
  237.  
  238.      'Process file' reads the file from disk and changes it according to your
  239. preferences.  To save the processed file, use 'Save' from the Project menu.
  240.      'Process & Crunch' will process the file and crunch the file afterwards
  241. (if possible).  To save use 'Save' in the Project menu.
  242.  
  243. Note: - Debug and symbol hunks are only used in debuggers, so you can safely
  244.         remove them from a program. (Unless you want to debug the program.)
  245.  
  246. 3. The Script Menu
  247. ------------------
  248.  
  249.      The script is something that will save you a lot of time, it allows you
  250. to record 80 different commands to be executed after each other.  It is ideal
  251. for crunching a lot of files overnight.  Menu options are:
  252.  
  253.      'Clear Script' and 'List Script':
  254.           will do just that.
  255.      'Script Log File':
  256.           is used to specify a file to redirect output to.  If you cancel
  257.           the requester no log file is used.
  258.      'Destination Dir':
  259.           is used to specify the directory to save to.  It is ghosted in
  260.           normal use.
  261.      'Start Recording':
  262.           is used to start the recording of the script. If the script was
  263.           empty you will be asked for the destination directory.  You will
  264.           also be asked whether to append '.pp22' to the destination file.
  265.           You're advised to do this for data files.
  266.               After selecting the destination you can start entering the
  267.           script commands.  Everything that is ghosted is not available as a
  268.           command.  Just enter everything as if you were actually using the
  269.           PowerPacker.  When you e.g. choose 'Load' the PowerPacker will
  270.           ask a list of files to be (de)crunched. Press 'CANCEL' to exit the
  271.           entry.
  272.           Note: - You can still change the source and destination dir while
  273.                   recording.
  274.           Every command you enter will be displayed in the supervisor window.
  275.      'Stop Recording':
  276.           is used to exit the recording mode.
  277.      'Delete Last':
  278.           will delete the last command after a confirmation.
  279.      'Execute Script':
  280.           will start the playback of the script commands.  If you press the
  281.           menu button a requester will appear to ask you if you want to abort
  282.           the script execution.
  283.               After executing the script a request to clear the script will
  284.           appear.
  285.  
  286. Note: - It is advisable to let the filerequester buffer fill before you
  287.         start selecting files.  It is also better not to change the source
  288.         directory too often.
  289.       - The screen turns grey to indicate a script is executing.
  290.       - While executing a script, the PowerPacker will always act
  291.         destructive !  Files will allways be overwritten and deleted !!!
  292.  
  293. 4. The Supervisor Window
  294. ------------------------
  295.  
  296.      This window displays all kind of useful information like the file
  297. status, crunch messages, and error messages.  You can follow all steps, from
  298. the original file that is loaded into memory, to the final crunched version
  299. on disk.  When an executable file is loaded, its hunk information is
  300. displayed.  This information is rather technical, but it can be useful for
  301. programmers.  If you're not interested, just ignore it.
  302.  
  303.      I think it might be useful to give a list of possible error messages:
  304.  
  305. (De)crunch :  Buffer overflow !
  306.                 (Crunched file is getting longer than original file)
  307.               Crunch aborted !
  308.                 (Crunching stopped by user or by buffer overflow)
  309.               No memory for decrunch buffer !
  310.               Out of memory !
  311.                 (Buy some more, try selling your WorkBench :-)
  312.               Sorry, can't crunch !
  313.                 (This is a polite program)
  314.               Can't find hunk_header.
  315.               Hunk not allowed in load file!
  316.               Unknown Hunk !
  317.                 (Not a command file)
  318.               Hunk not supported (yet ?) !
  319.                 (If it's a symbol or debug hunk, try removing it in HunkLab)
  320.               Nothing to save !
  321.                 (Buffer is empty)
  322.               Save Aborted !
  323.               Error reading file !
  324.               Can't open file !
  325.               Error writing data header !
  326.               Error writing buffer !
  327.               File not found !
  328.               Couldn't delete file !
  329.               Can't open file !
  330.                 (Disk errors)
  331.  
  332. Recrunch :    No need to recrunch 'PowerPacker 1.1' command file,
  333.               Replacing 1.1 decrunch header with 2.2 header...
  334.                 (2.2 header is shorter and bugfree, 1.1 isn't !!)
  335.               No need to recrunch 'PowerPacker 2.0' command file,
  336.               Replacing 2.0 decrunch header with 2.2 header...
  337.                 (There was still a small bug in 2.0 header, so replace it.)
  338.               Not crunched with one of the supported crunchers !!
  339.                 (Or file isn't crunched at all !)
  340.               Sorry, can't recrunch !
  341.                 (Please don't sue me :-)
  342.  
  343. Process :     Sorry, can't process file !
  344.                 (File is probably not a command file)
  345.               Can't crunch file !
  346.                 (File contains unsupported hunks)
  347.  
  348. Script :      Script buffer full !! Please stop recording.
  349.                 (Script is limited to 80 commands, select 'Stop Recording')
  350.  
  351. 5. A Sample Session
  352. -------------------
  353.  
  354.      Now that I have explained the PowerPacker's capabilities, it's time for
  355. a little demonstation.  Let's say we want to crunch the 'CLI' command in the
  356. System directory on your Workbench 1.2 disk.
  357.  
  358.      Select 'Pointer' in the Prefs/Decrunch Color menu (When I wrote this
  359. text, it was very late and I couldn't stand the other decrunch colors
  360. anymore !)
  361.  
  362.      Set 'Prefs' to 'Command file'.  Now select 'Load' in the Project menu
  363. (a file requester will appear), insert your WorkBench 1.2 disk and choose the
  364. 'CLI' command in the system directory.  Now you'll see a lot of hunk
  365. information about the CLI command:
  366.  
  367.  
  368. Loading command file 'df0:System/CLI'...
  369.  
  370.      Hunk_header (0x03F3)
  371.         9 hunks (0 to 8).
  372.      Hunk  0 : Hunk_code (0x03E9)     (524 bytes)
  373.                Hunk_reloc32 (0x03EC)
  374.      Hunk  1 : Hunk_data (0x03EA)     (428 bytes, 0 BSS)
  375.      Hunk  2 : Hunk_code (0x03E9)     (472 bytes)
  376.                Hunk_reloc32 (0x03EC)
  377.      Hunk  3 : Hunk_data (0x03EA)     (52 bytes, 0 BSS)
  378.      Hunk  4 : Hunk_code (0x03E9)     (16 bytes)
  379.      Hunk  5 : Hunk_code (0x03E9)     (0 bytes)
  380.      Hunk  6 : Hunk_code (0x03E9)     (196 bytes)
  381.                Hunk_reloc32 (0x03EC)
  382.      Hunk  7 : Hunk_code (0x03E9)     (68 bytes)
  383.                Hunk_reloc32 (0x03EC)
  384.      Hunk  8 : Hunk_data (0x03EA)     (0 bytes, 0 BSS)
  385.  
  386.      Crunching command file...
  387.      Press left and right button to abort.
  388.      Crunching, please wait.
  389.  
  390.      The cruncher displays the percentage of the file already crunched and
  391. the gain so far. After some time your screen will look like this:
  392.  
  393.  
  394.      100% crunched.
  395.      Done.
  396.      Original length : 2356 bytes.
  397.      Crunched length : 1204 (1776) bytes.
  398.      Gained 49% (1152 bytes) !
  399.  
  400. The only thing you have to do now is save this back to disk as an
  401. executable file.  Now enjoy the crunched CLI command.
  402.  
  403.  
  404. 6. PowerPacker 2.2a & the CLI
  405. -----------------------------
  406.  
  407.      For your convenience, I have also written two CLI commands, one to
  408. crunch and one to decrunch.
  409.      Attention:  These commands only (de)crunch DATA files !!!!  (So to
  410. crunch executable files, you'll still have to use the PowerPacker 2.2a).
  411.      A usage line is given by typing 'Crunch' or 'Decrunch' without
  412. arguments.  You'll get something like this:
  413.  
  414. 1>
  415. 1> crunch
  416. POWER-PACKER 2.2a Data Cruncher.
  417.   Written by Nico François (POWER PEAK)
  418. USAGE : Crunch <source> <destination> [efficiency (1-5) default 3] [P] [F]
  419.         Where P stands for no percentage, F for Forbid() crunching.
  420. 1>
  421. 1> decrunch
  422. POWER-PACKER 2.2a Data Decruncher.
  423.   Written by Nico François (POWER PEAK)
  424. USAGE : Decrunch <source> <destination> [decrunch color (0-4)]
  425.    With decrunch color 0/1 -> Color 0/1, 2 -> Pointer, 3 -> Scroll, 4 -> None
  426.    If <destination> is a * the file will be typed to Output().
  427. 1>
  428.  
  429.      These commands are useful to be included in your startup-sequence or to
  430. read crunched text files quickly.
  431.  
  432.      I don't think these commands need any further explanation.  They work
  433. just like the CLI Copy command.  Just try them out and you'll see what
  434. happens.  E.g. when you have a crunched source file of a program on your
  435. disk, typing
  436.  
  437.      Decrunch filename.c *
  438.  
  439. will display the file as if you were using the 'Type' command for textfiles.
  440.  
  441.                                                    Enjoy !!!
  442.  
  443.  
  444.                               PROGRAM HISTORY:
  445.  
  446. *****************************************************************************
  447. VERSION 1.0a
  448.  
  449.      First release.
  450.  
  451. *****************************************************************************
  452. VERSION 1.1a
  453.  
  454.      Fixed bugs.
  455.      Improved crunch algorithm by about 5%.
  456.      'Delete' and 'Multitask' added.
  457.      Better menu structure.
  458.      Improved the file requester.
  459.      Written CLI commands.
  460.  
  461. *****************************************************************************
  462. VERSION 2.0a
  463.  
  464.      Fixed some more bugs.
  465.      Added buffer and automatic device-list to the file requester.
  466.      Added 'LED Crunch', useful for turning the monitor off while crunching,
  467.      and 'Paging'.
  468.      New header, bug fixed. (1.1 didn't free mem when started from WorkBench)
  469.      Added the hunklab.
  470.      Improved CLI commands.
  471.  
  472. *****************************************************************************
  473. VERSION 2.1a
  474.  
  475.      Fixed last bug in header (2.0 crashed when you were out of memory, oops)
  476.      Added script feature, now possible to crunch files overnight.
  477.      Improved requesters.
  478.      Automatic crunch/decrunch.
  479.      Improved menu structure considerably.
  480.      Intelligent recrunch implemented.
  481.      Automatic crunch/decrunch.
  482.      Added 'Color Crunch' option.
  483.      New efficiency 'Best' added.
  484.  
  485. *****************************************************************************
  486. VERSION 2.1b
  487.  
  488.      Bug fixed in script abort.
  489.      Added ability to open a log file during script execute.
  490.      Now possible to recrunch PowerPacker files with a higher efficiency.
  491.      Recrunch detects unsupported crunchers a lot faster.
  492.      The PowerPacker now automatically opens a PAL/NTSC screen.
  493.  
  494. *****************************************************************************
  495. VERSION 2.2a
  496.  
  497.      All known bugs (or better, undocumented features) fixed.
  498.      'Sleep' mode implemented, useful for multitasking freaks.
  499.      While crunching the gain percentage so far is displayed.
  500.      Recrunch now supports 'HQC Cruncher 2.0', 'MasterCruncher 3.0'
  501.        and 'Dragpack 1.0'.
  502.      New graphics in title.
  503.  
  504. *****************************************************************************
  505.  
  506.  
  507. P.S. This text file crunches to 42% of it's original length. (Gains 58% !)
  508.  
  509. The PowerPacker 2.2a written by Nico François. (Yes, Nico is my first name)
  510. Special thanks to Pauwels Luc for the icons and writing the 2.0a manual,
  511.                   Tybergein Jorrit for the extensive debugging.
  512.  
  513. (c) 1989 Nico François / Power Peak
  514.  
  515.                                    //
  516.                        Thanks to \X/ Amiga for being the best computer ever !
  517.  
  518.